% cGENIE HOW-TO document

% Andy Ridgwell, March 2011
%
% ---------------------------------------------------------------------------------------------------------------------------------
% 11/03/24: added 'Determine the CH4 flux required to achieve a particular atmospheric pCH4 value'
% 11/04/06: added 'Prescribe a spatial map of benthic tracer release'
% 11/08/02: added data-saving info
% ---------------------------------------------------------------------------------------------------------------------------------

\documentclass[10pt,twoside]{article}
\usepackage[paper=a4paper,portrait=true,margin=2.5cm,voffset=0pt,ignorehead,footnotesep=1cm]{geometry}
\usepackage{graphicx}
\usepackage{hyperref}
\usepackage{paralist}
\usepackage{caption}
\usepackage{float}
\usepackage{wasysym}

\linespread{1.1}
\setlength{\pltopsep}{2.5pt}
\setlength{\plparsep}{2.5pt}
\setlength{\partopsep}{2.5pt}
\setlength{\parskip}{2.5pt}

\title{cGENIE HOW-TO}
\author{Andy Ridgwell}
\date{\today}

\begin{document}


%=================================================================================================================================
%=== BEGIN DOCUMENT ==============================================================================================================
%=================================================================================================================================

\maketitle


%=================================================================================================================================
%=== CONTENTS ====================================================================================================================
%=================================================================================================================================

\tableofcontents


%=================================================================================================================================
%=== CHAPTERS ====================================================================================================================
%=================================================================================================================================


%---------------------------------------------------------------------------------------------------------------------------------
%--- Introduction ----------------------------------------------------------------------------------------------------------------
%---------------------------------------------------------------------------------------------------------------------------------

\newpage
\section{Introduction}\label{Introduction}

This document provides HOW-TO's for cGENIE users; where obvious changes are made; now items include instructions for speeding up the model and incorporation of (ocean) cadmium.


%---------------------------------------------------------------------------------------------------------------------------------
%--- HOW-TOs: Getting started ----------------------------------------------------------------------------------------------------
%---------------------------------------------------------------------------------------------------------------------------------

\newpage
\section{HOW-TOs: Getting started}\label{how-to-0}


%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Do some thing dumb}\label{Do some thing dumb}

Easy! Just close your eyes and change some parameter values at random. Better still, start using the model without reading the manual first ...


%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Install \texttt{cGENIE}}\label{Install cGENIE}

See: \texttt{cGENIE} \textit{Quick-start Guide}. (Also refer to the \texttt{READ-ME} file for e.g., details of changes in configuring and running \texttt{cGENIE} compared to \texttt{GENIE}.)


%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Find configurations for \texttt{cGENIE}}\label{Find configurations for cGENIE}

A series of (example) \texttt{cGENIE} configurations are provided, many of which are detailed in full in the \texttt{cGENIE} \textit{Tutorial} document.
Example configurations comprise \textit{base-config} and \textit{user-config} files, plus any \textit{forcings} needed.
\begin{compactitem}
	\item
  \texttt{cGENIE} \textit{base-configs} are stored in:
	\\ \texttt{~/cgenie/genie-main/configs}
	\\and all start with '\texttt{cgenie\_}', for example: \\ \texttt{cgenie\_eb\_go\_gs\_ac\_bg\_hadcm3l\_eocene\_36x36x16\_2i\_080928\_BASE.config}
	\item
	\texttt{cGENIE} user configs are stored in:
	\\ \texttt{~/cgenie/genie-userconfigs}
	\item
	\texttt{cGENIE} forcings are stored in:
	\\ \texttt{~/cgenie/genie-forcings}
\end{compactitem}


%---------------------------------------------------------------------------------------------------------------------------------
%--- HOW-TOs: General ------------------------------------------------------------------------------------------------------------
%---------------------------------------------------------------------------------------------------------------------------------

\newpage
\section{HOW-TOs: General}\label{how-to-1}

%---------------------------------------------------------------------------------------------------------------------------------


%---------------------------------------------------------------------------------------------------------------------------------
%--- HOW-TOs: Model output -------------------------------------------------------------------------------------------------------
%---------------------------------------------------------------------------------------------------------------------------------

\newpage
\section{HOW-TOs: Model output}\label{how-to-2}

%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Set the frequency of time-series and time-slice output}\label{how-to-2a}

See: \textit{c}GENIE \textit{user-manual} (section 5).

%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Diagnose orbital (insolation) changes}\label{how-to-2b}

Two new \texttt{misc} category time-series files have been provided:
\vspace{-10pt}\begin{verbatim}biogem_series_misc_ocn_insol.res\end{verbatim}\vspace{-10pt}
and
\vspace{-10pt}\begin{verbatim}biogem_series_misc_ocn_swflux.res\end{verbatim}\vspace{-10pt}
with the the SW (shortwave) flux (\texttt{swflux}) being equivalent to the incident strength of solar radiation at the surface (\texttt{insol}) but accounting for the prescribed planetary albedo. Both variables are calculated and saved on a global mean ocean grid basis (2nd data column) and have units of W m-2.
\\In addition, to help diagnose orbital variability, \texttt{biogem\_series\_misc\_ocn\_insol.res} includes two further insolation variables (3rd and 4th columns). These reflect the strength of insolation at a single point in the annual cycle and at discrete latitudes (i.e. \texttt{j} grid indices). (The insolation at 2 different latitudes are saved so that both .e.g. N and S hemisphere insolation signals can be simultaneously recorded.)
\\Three new namelist parameters are provided to configure this:
\begin{compactenum}
	\item \texttt{bg\_par\_t\_sig\_count} -- which sets the BIOGEM 'time-step' in the annual cycle at which the insolation value will be saved. e.g. for 96 time-steps in the ocean physics, and a 2:1 GOLDSTEIN:BIOGEM gearing (the default for the 16 level configuration), there are 48 BIOGEM time-steps. (It is left to the user to work out which part of the annual cycle \textit{c}GENIE starts at (i.e. time-step \#1) -- I haven't a clue ...)
	\item \texttt{bg\_par\_sig\_j\_N} -- sets the 'j' value for a northern hemisphere (but could be southern) snap-shot.
	\item \texttt{bg\_par\_sig\_j\_S} -- sets the 'j' value for a southern hemisphere snap-shot.
\end{compactenum}


%---------------------------------------------------------------------------------------------------------------------------------
%--- HOW-TOs: Climate ------------------------------------------------------------------------------------------------------------
%---------------------------------------------------------------------------------------------------------------------------------

\newpage
\section{HOW-TOs: Climate}\label{how-to-3}

%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Adjust solar forcing in a time-dependent manner}\label{Adjust solar forcing in a time-dependent manner}

The value of the solar constant in cGENIE is set by the \textit{namelist parameter}:
\\ \texttt{ma\_genie\_solar\_constant} and by default is set to 1368 W m-2, i.e.:
\vspace{-10pt}\begin{verbatim}ma_genie_solar_constant=1368.0\end{verbatim}\vspace{-5pt}
Specifying a different value for \texttt{ma\_genie\_solar\_constant} in the user config file allows the solar forcing of the EMBM to be altered. For example, to induce a 'snowball Earth' like state under a solar constant applicable to the late Neoproterozoic (some 6\% less than modern) you would set:
\vspace{-10pt}\begin{verbatim}ma_genie_solar_constant=1330.56\end{verbatim}\vspace{-5pt}

Modification of \texttt{ma\_genie\_solar\_constant} can be turned into a time-dependent forcing of solar forcing, but only by frequent re-starting using a sequence of short model integrations.

Alternatively, a crude (temporary) hack is provided to allow a semi-continual adjustment of solar forcing. Whether you wish to vary the solar constant in a time-dependent manner is determined by the \textit{parameter}:\\
\texttt{bg\_ctrl\_force\_solconst}. By default this is set to \texttt{.false.}. By adding to the user config file:
\vspace{-10pt}\begin{verbatim}bg_ctrl_force_solconst=.true.\end{verbatim}\vspace{-5pt}
a time-varying change in the value of the solar constant will be imposed. For this, BIOGEM will expect the presence of a file called \texttt{biogem\_force\_solconst\_sig.dat} in the forcing directory\footnote{REMEMBER: The location of which is specified by the namelist parameter bg\_par\_fordir\_name.}.

\texttt{biogem\_force\_solconst\_sig.dat} must contain two columns of information: the first is a time marker (year) and the second is a paired value for the solar constant. In the current crude incarnation of this feature, the time markers (1st column) \textbf{must} correspond exactly to the time markers in the time-series specification file\footnote{REMEMBER: The filename of which is specified by the namelist parameter bg\_par\_infile\_sig\_name.}. GENIE will exit with an appropriate error message if this is not the case.

Seasonal solar insolation is re-calculated each year with a call to:
\vspace{-10pt}\begin{verbatim}radfor(genie_solar_constant)\end{verbatim}\vspace{-5pt}
(EMBM file: \texttt{radfor.F}) at the start of the time-stepping loop in \texttt{genie.F}. At each time-marker, BIOGEM sets the value of \texttt{genie\_solar\_constant} equal to the corresponding value specified in:\\
\texttt{biogem\_force\_solconst\_sig.dat}. Thus, regardless of how closely-spaced the time-marker years are, (seasonal) solar insolation is only adjusted every year. For a longer time-marker interval than yearly, no interpolation is performed on the series of solar constant values, and in this way time-dependint solar forcing currently differs from the calculation of other forcings.

EXAMPLE: A simple file might look something like:
\vspace{-5pt}\begin{verbatim}
-START-OF-DATA-
 0.5   1367.0
 1.5   1366.0
 2.5   1365.0
 3.5   1364.0
 4.5   1363.0
 5.5   1362.0
 6.5   1361.0
 7.5   1360.0
 8.5   1359.0
 9.5   1358.0
10.5   1357.0
-END-OF-DATA-
\end{verbatim}\vspace{-5pt}
which will decrease the value of the solar constant by 1 W m-2 each year. Note that because the solar forcing is only updated each year (with the call to \texttt{radfor.F}), the first year will be characterized by climate with a solar constant of 1368 W m-2, the default. Although BIOGEM sets a new value of \texttt{genie\_solar\_constant} (1367 W m-2) mid way through the first year, it is only at the start of the second year that solar insolation is recalculated according to the reduction in solar constant.


%---------------------------------------------------------------------------------------------------------------------------------
%--- HOW-TOs: Ocean biology and biogeochemical cycling ---------------------------------------------------------------------------
%---------------------------------------------------------------------------------------------------------------------------------

\newpage
\section{HOW-TOs: Ocean biology and biogeochemical cycling}\label{how-to-4}

%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Configure an abiotic ocean}\label{Have an abiotic ocean}

Biological productivity in the ocean can be completely turned off to create an abiotic ocean (why you would want to do this is another matter ... perhaps analyzing the solubility pump or a 'deep-time' and prior to significant marine life study ... (?)). The biological option is set by the \textit{parameter} \texttt{bg\_par\_bio\_prodopt} which by default takes a value of \texttt{"1N1T\_PO4MM"} which selects the scheme described in \textit{Ridgwell et al.} [2007a]. To have no biological production in the ocean, add the following line to the end of the \textit{user-config} file (or edit the existing line in the section '\texttt{--- BIOLOGICAL NEW PRODUCTION ---}'):
\vspace{-11pt}\begin{verbatim}
bg_par_bio_prodopt="NONE"
\end{verbatim}\vspace{-5.5pt}
With this set, you do not have to specify any biological production or remineralization namelist parameter values in the \textit{user-config} file.


%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Specify the CaCO3:POC export ratio}\label{CaCO3:POCrainratio}

In the default\footnote{The default biological scheme is given by: \texttt{bg\_par\_bio\_prodopt='1N1T\_PO4MM'}.} 'biological' scheme in GENIE the CaCO3:POC export ratio from the surface ocean in BIOGEM is parameterized as a power law function of the degree of ambient oversaturation w.r.t. calcite [\textit{Ridgwell et al.}, 2007a,b]. The calculated CaCO\begin{math}_3\end{math}:POC ratio will vary therefore both spatially, particularly w.r.t. latitude (and temperature), as well as in time, if the surface ocean saturation state changes. The latter can arise from climatic (temperature) or circulation changes, or through a change in the DIC and/or ALK inventory of the ocean (such as resulting from emissions of fossil fuel CO2) or the re-partitioning of these species vertically within the ocean (e.g., as a result of any change in the strength of the biological pump).

There may be situations in which it is advisable to hold the CaCO\begin{math}_3\end{math}:POC export ratio invariant. For instance, considering the current very considerable uncertainties in the impacts of ocean acidification on marine calcifiers [\textit{Ridgwell et al.}, 2007a] the safest assumption is arguably to exclude any acidification impact on calcification and carbonate export. Specifying a spatially uniform value of the CaCO\begin{math}_3\end{math}:POC ratio ratio (e.g. 0.25 or 0.3) also allows comparison with the results of early carbon cycle model studies. For deeper-time geological studies where little about marine carbonate production may be known \textit{a priori}, a spatially uniform value represents the simplest possible assumption (e.g., \textit{Panchuk et al.} [2008]).

BIOGEM can be told to use a prescribed (spatially and temporally invariant) 2D field of CaCO\begin{math}_3\end{math}:POC export rain ratios (instead of calculating these internally as a function of ocean chemistry) by setting the 'Replace internal CaCO3:POC export rain ratio?' namelist flag to \texttt{.true.}:
\vspace{-5.5pt}\begin{verbatim}
bg_ctrl_force_CaCO3toPOCrainratio=.true.
\end{verbatim}\vspace{-5.5pt}
You must also then provide a 2D data field that specifies the value of the rain ratio at each and every surface ocean grid point. The filename of this field is set by default to:
\vspace{-5.5pt}\begin{verbatim}
bg_par_CaCO3toPOCrainratio_file="CaCO3toPOCrainratio.dat"
\end{verbatim}\vspace{-5.5pt}
and the file must be located in the 'BIOGEM data input directory'\footnote{\texttt{\$RUNTIME\_ROOT} being equal to \texttt{\~{}/genie}.}, which by default is:
\\\texttt{bg\_par\_indir\_name="} \texttt{\$RUNTIME\_ROOT/genie-biogem/data/input"}

This 2-D field must be in the form of an ASCII file with space (or tab) separated values arranged in rows and columns of latitude and longitude. The format of the file must follow the GOLDSTEIN ocean grid with the first line being the most Northerly row, and the last line the most Southerly row of grid points. Data along a row is from West to East. The latitude of the first column of values must be consistent with the defined starting latitude of the model grid, which is specified by the namelist parameter \texttt{gm\_par\_grid\_lon\_offset}\footnote{-260E by default}. Examples are given in the code repository\footnote{e.g., \texttt{\~{}/genie/genie-biogem/data/input/CaCO3toPOCrainratio\_worbe2\_preindustrial.dat}}.

If you are using a uniform value, it is an easy enough job to create a \begin{math}36\times36\end{math} array of the value you so desire\footnote{It doesn't matter if you specify a value over land because only values associated with wet cells will be acted on.}.

If you want to hold a previously-calculated (spatially variable) CaCO\begin{math}_3\end{math}:POC field constant, then the easiest way to achieve this is to copy the information contained in the \textit{time-slice} results field:\\
\texttt{misc\_sur\_rCaCO3toPOC} in the results netCDF file \texttt{fields\_biogem\_2d.nc}\footnote{You must have the 'miscellaneous properties' time-slice save flag set to:\\
\texttt{bg\_ctrl\_data\_save\_slice\_misc=.true.} (the default) for this field to be saved.}. Because this is a 3D data field (\begin{math}36\times36\times8\end{math}), carefully highlight just the surface ocean (2D) distribution (e.g., from the Panoply viewer) or extract from the netCDF file by some other means, and then copy and paste into:\\
\texttt{CaCO3toPOCrainratio.dat} (or whatever you have specified the filename as). When copying Panoply data, 'NaN's should be replaced by values of zero. Take care that the final (steady-state) time-slice is being copied and not the first (un-spunup) one ...

\textbf{TIP}: In order to quantify the importance of calcification feedbacks with CO2 and climate, two model integrations are required: one with the CaCO\begin{math}_3\end{math}:POC ratio held constant and the other with it allowed to vary, thereby allowing the effect of a changing CaCO\begin{math}_3\end{math}:POC ratio on the system to to elucidated.

%---------------------------------------------------------------------------------------------------------------------------------


%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Implementing an alternative fixed remineralization profile for POC (e.g. Martin curve)}\label{fixedremin}

There are several options for utilizing a fixed remineralization profile for POC, which by default is a double exponential (See: \textit{Ridgwell et al.} [2007a]).
The fixed remineralziation profile scheme is set by the string parameter: \texttt{bg\_par\_bio\_remin\_fun}. By default, it has a value of '\texttt{efolding}'. Currently available options are:

\begin{compactitem}
	\item
  \texttt{Martin1987}, which applies a globally-uniform power, set by:
  \\ \texttt{bg\_par\_bio\_remin\_martin\_b}
  \\(which by default has a value of -0.858)
	\item
  \texttt{Henson2012}, which calculates the value of b according to sea surface temperature (SST):
  \\b = (0.024 * SST) - 1.06
\end{compactitem}

To user either (on their own), all organic matter should be assigned to a single phase, with the 2nd (recalcitrant) fraction set to zero:
\vspace{-5.5pt}\begin{verbatim}
bg_par_bio_remin_POC_frac2=0.0
\end{verbatim}\vspace{-5.5pt}

Note that these parameterizations can be combined with ballasting \ref{ballasting} and will act on the 'free' POC phase (i.e. the one not controlled by the ballasting parameterization).

%---------------------------------------------------------------------------------------------------------------------------------


%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Implement particulate organic carbon 'ballasting'}\label{ballasting}

The default particulate organic carbon (POC) ocean interior remineralization scheme is based on fixed, prescribed profiles of relative POC flux to depth (e.g. see: \textit{Ridgwell} [2001]; \textit{Ridgwell et al.} [2007a]). A 'ballasting' control on POC transport to depth can instead be implemented by:
\vspace{-5.5pt}\begin{verbatim}
bg_ctrl_bio_remin_POC_ballast=.true.
bg_ctrl_bio_remin_POC_fixed=.false.
\end{verbatim}\vspace{-5.5pt}

The POC 'carrying coefficients' for CaCO3, opal, and detrital (lithogenic) material are set by the parameters:
\vspace{-5.5pt}\begin{verbatim}
bg_par_bio_remin_ballast_kc
bg_par_bio_remin_ballast_ko
bg_par_bio_remin_ballast_kl
\end{verbatim}\vspace{-5.5pt}
(for CaCO3, opal, and lithogenics, respectively). Note that the ballast coefficient units are: g POC m-2 yr-1 (g ballast m-2 yr-1)-1 (i.e. \textbf{g g-1}), which are internally converted to: mol POC m-2 yr-1 (mol ballast m-2 yr-1)-1 (i.e. \textbf{mol mol-1}).

If the \verb=bg_ctrl_bio_remin_POC_fixed= is kept to  \verb=.true.=(default). Then the POC flux is a function of the \textbf{surface} CaCO3, opal and lithogenic export flux. Ballasting carrying coefficients are typically based on empirical relationships between POC flux at depth to the CaCO3/opal/lithogenic flux at \textbf{depth}. This is why \verb=bg_ctrl_bio_remin_POC_fixed= should be set to \verb=.false.= when using standard carying coefficients. Please note that keeping that option to \verb=.true.= is equivalent to ignoring the effect of CaCO3 remineralisation on the POC flux. 

A fixed (in time), but spatially heterogeneous field can also be prescribed instead of global uniform values (akin to setting a pattern of the CaCO3:POC export rain ratio (\ref{CaCO3:POCrainratio}). The parameters setting whether to substitute a globally-uniform value with a specified pattern are:
\vspace{-5.5pt}\begin{verbatim}
bg_ctrl_force_CaCO3ballastcoeff=.true.
bg_ctrl_force_opalballastcoeff=.true.
bg_ctrl_force_detballastcoeff=.true.
\end{verbatim}\vspace{-5.5pt}
and which by default are \texttt{.false.}.
The patterns of carrying coefficient are determined by files read in from \texttt{cgenie\slash genie-biogem\slash data\slash input}. The filenames are specified by:
\vspace{-5.5pt}\begin{verbatim}
bg_par_CaCO3ballastcoeff_file
bg_par_opalballastcoeff_file
bg_par_detballastcoeff_file
\end{verbatim}\vspace{-5.5pt}
(again, akin to the methodology for setting the CaCO3:POC export rain ratio (\ref{CaCO3:POCrainratio})).

Note that ballasting is combined with an e-folding (or other) fixed profile remineralization schemes. Ballasting is calculated with respect to the 2nd (recalcitrant) fraction of POC only. The remaining POC export is be degraded by an alternative algorithm, which by default, is an e-folding decay (see \ref{fixedremin} for more and alternatives). The fraction of initial export assigned to ballasting vs. 'free' POC is calculated according to the available exported ballast flux.

%---------------------------------------------------------------------------------------------------------------------------------


%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Prescribe biological export production}\label{Prescribe biological export production}

Two possibilities:

\begin{compactenum}

	\item \textbf{Via a full prescription of all particulate fluxes in surface ocean}
		\\Create a full set of particulate (sediment tracer) flux forcings fields for the surface ocean, one for each biologically-related sediment tracer selected in the model, including isotopes (and trace metals). Everything except for the surface layer can be left as a zero (0.0) in the two 3D spatial fields required for each tracer.
  	\\You must also create a set of dissolved (ocean) tracer flux forcings fields for the surface ocean, one for each dissolved tracer associated with the particulates and selected in the model (including isotopes etc). The dissolved tracer flux fields must be create so as to exactly cancel out the particulate fields to conserve mass. For most tracers this is trivial, i.e., the fields for P in particulate organic matter (sed\_POP) need be associated with fields for dissolved PO4 (ocn\_PO4) which will simply be equal in magnitude but opposite in sign to POP. Complications start to arise for CaCO3 (2 alklinities) and there is also the question of alkalinity changes associated with organic matter creation/destruction (via changes in NO3).
	
	\item \textbf{By just prescribing just the POC flux}
		\\An alternative has been provided enabling a full biological productivity in the surface ocean, but controlled by prescribing just the particulate organic carbon export flux. This 'biological' scheme is selected with::
\vspace{-5.5pt}\begin{verbatim}bg_par_bio_prodopt="bio_POCflux"\end{verbatim}\vspace{-5.5pt}
What happens in practice is that the POC flux is used to calculate the equivalent PO4 change in the surface ocean, and then this is passed to the biological scheme and export production calculated 'as usual'. (The POC flux forcing is set to zero once the associated PO4 (uptake) flux has been calculated.)
		\\A particulate (sediment tracer) flux forcing for POC in the surface ocean still has to be defined and selected, but no other forcings (including dissolved) are required. An example forcing configuration is given in \texttt{EXAMPLE\_bio\_POCflux} (and which can be obtained form mygenie.seao2.org) and would naturally be selected by:
\vspace{-5pt}\begin{verbatim}bg_par_forcing_name="TEST_bio_POCflux"\end{verbatim}\vspace{-5pt}

\noindent \textbf{NOTE}: Take care with dissolved organic matter (DOM) production, as a fraction of the specified POC flux will be converted into POC (and similarly for the other components of POM). Simplest is to set no DOM production if you are uncertain:
\vspace{-5pt}\begin{verbatim}bg_par_bio_red_DOMfrac=0.0\end{verbatim}\vspace{-5pt}
\noindent \textbf{NOTE}: Also take care with the units of the flux forcing to the surface layer in the ocean (mol yr-1). Since GENIE-1 is often run on a equal area grid, it is not difficult to convert export production densities to mol yr-1. However, with an equal area grid, whatever the units are of the desired POC export field are do no matter -- the global export can be set and the spatial distribution will then be appropriately scaled (as per in the \texttt{EXAMPLE\_bio\_POCflux} example). Also be aware that if there is insufficient PO4 to support the require POC flux, you will not get your entire POC flux. Global total export may thus be somewhat less than that specified.

\end{compactenum}

%---------------------------------------------------------------------------------------------------------------------------------


%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Include a R-DOM cycle in the ocean}\label{Include a R-DOM cycle in the ocean}


\subsubsection{R-DOM degradation}\label{R-DOM degradation}

The parameter: \texttt{bg\_ctrl\_bio\_remin\_RDOM\_photolysis} determines whether RDOM degradation is restricted to the surface layer and occurs only by/associated with photolysis. It can be \texttt{.true.} or \texttt{.false.} and by default is set to:
\vspace{-10pt}\begin{verbatim}bg_ctrl_bio_remin_RDOM_photolysis=.false.\end{verbatim}\vspace{-10pt}
When set \texttt{.true.}, RDOM degradation is set to zero everywhere in the ocean except the surface layer. Here, the lifetime (parameter: \texttt{bg\_par\_bio\_remin\_RDOMlifetime}) is modified in *inverse* proportion to the solar insolation integrated over the surface layer. (There is a field in the 2D netCDF of solar insolation at the ocean surface, and the average over the surface layer is approx ~1/4 of this.). i.e., in lower latitude and higher insolation regions, the lifetime is shorter than specified by \texttt{bg\_par\_bio\_remin\_RDOMlifetime} (and by approx a factor of 1/4 of the solar insolation in W m-2).


%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Include a Cd cycle in the ocean}\label{Include a Cd cycle in the ocean}


In order to run cGENIE with ocean cadmium cycle, the following \textit{base config}: \\ \texttt{cgenie\_eb\_go\_gs\_ac\_bg\_itfclsd\_16l\_JH\_BASEFeCd} is provided (under SVN).

A typical experiment command line, using the \textit{user config} file: \texttt{EXAMPLE\_worjh2\_PO4Fe\_Cd\_SPIN} (also provided under SVN), would look like:
\vspace{-5.5pt}\begin{verbatim}
./runCCgenie.sh cgenie_eb_go_gs_ac_bg_itfclsd_16l_JH_FeCdBASE /
  EXAMPLE_worjh2_FeCd_SPIN 11
\end{verbatim}\vspace{-5.5pt}

To submit this job to the cluster (from \$HOME):
\vspace{-5.5pt}\begin{verbatim}
qsub -q kitten.q -j y -o cgenie_log -S
  /bin/bash subcgenie.sh cgenie_eb_go_gs_ac_bg_itfclsd_16l_JH_BASEFeCd /
  EXAMPLE_worjh2_PO4Fe_Cd_SPIN 10001
\end{verbatim}\vspace{-5.5pt}


%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Determine the CH4 flux required to achieve a particular atmospheric pCH4 value}

Unlike the concentration of CO2 in the atmosphere, which if restored to a chosen value during a \textit{spin-up} experiment, will remain at that value in a \textit{continuation} experiment (if no other perturbation of the carbon cycle or CO2 emissions have been prescribed), CH4 in the atmosphere decays with a lifetime of ca. 8 years (with a small fraction dissolving in ocean surface waters and being oxidized in the ocean). Hence, atmospheric CH4 \textit{restored} to a particular value in a spin-up, requires that restoring to be maintained in any \textit{continuation} experiment or CH4 will quickly decay to zero. However, doing this (\textit{restoring} CH4 concentrations), prevents the effect of CH4 emissions on being assessed (as the atmospheric composition is being help constant).\\
An alternative would be carry out the \textit{spin-up} experiment with no \textit{restoring} of atmospheric CH4 (or \textit{restoring} to zero), and then run the \textit{continuation} experiment with no CH4 \textit{restoring}. This would enable e.g. CH4 emissions experiments to be carried out and the change in atmospheric CH4 in response to be simulated. The problem here is that the lifetime of CH4 in the atmosphere scales with the CH4 concentration. So in starting with no CH4 in the atmosphere, the CH4 lifetime is relatively short, and the response to CH4 emissions will be underestimated.\\
What is in effect 'missing' are the (natural) sources of CH4 to the atmosphere such as wetlands, which at steady state, provide a CH4 flux that balances the oxidation rate of CH4 in the atmosphere (and ocean). cGENIE has a \textit{parameter} for this: \texttt{ac\_par\_atm\_wetlands\_FCH4} (mol yr-1) (with the isotopic composition of this source set by: \texttt{ac\_par\_atm\_wetlands\_FCH4\_d13C}). All that then remains is to determine the flux of CH4 that balances the rate of oxidative loss for the desired atmospheric CH4 concentration. TO do this:
\begin{compactenum}
	\item Carry out a \textit{spin-up} with atmospheric CH4 \textit{restored} to the desired concentration.\footnote{For an example: see experiment \texttt{EXAMPLE\_p0055c\_PO4\_CH4\_SPIN} described in \textit{cGENIE.Examples}.}
	\item Determine the total loss rate of CH4 (including both atmospheric oxidation and invasion (and subsequent oxidation) into the ocean) -- this is recorded in the \textit{time-series} results file:\\ \texttt{biogem\_series\_focnatm\_pCH4.res}\footnote{Second column (the value in units of mol yr-1)}.
	\item Set the \textit{parameter} \texttt{ac\_par\_atm\_wetlands\_FCH4} equal to this value.
\end{compactenum} 
An example of a spin-up in which a prescribed ('wetland') flux of CH4 to the atmosphere is set, is described in:\\ \textit{cGENIE.Examples} -- \textit{spin-up} example \texttt{EXAMPLE\_p0055c\_PO4\_CH4\_SPIN2}


%---------------------------------------------------------------------------------------------------------------------------------
%--- HOW-TOs: System forcings ----------------------------------------------------------------------------------------------------
%---------------------------------------------------------------------------------------------------------------------------------

\newpage
\section{HOW-TOs: Forcings of the system}\label{how-to-5}

Note: All the \textit{forcings} described here assume the 'new' (simplified) methodology for prescribing forcings. This methodology is enabled by including the parameter setting:
\vspace{-10pt}\begin{verbatim}
bg_ctrl_force_oldformat=.false.
\end{verbatim}\vspace{-10pt}

Taking the example of the ocean (dissolved tracers): flux and restoring \textit{forcings} are defined in the \textit{forcings} specification file: \texttt{configure\_forcings\_ocn.dat}. As detailed in the notes to this file, there is a flag (\texttt{COLUMN \#6}) which sets the spatial attributes of the \textit{forcing} as follows: 
\vspace{-10pt}\begin{verbatim}
3 == 3D
2 == 2D
0 == point
-1 == SURFACE
-2 == BENTHIC
\end{verbatim}\vspace{-10pt}
the default (33) being that the forcing is applied uniformly to the entire (3D) ocean volume.

Options \texttt{3}, \texttt{2}, and \texttt{0}, as: uniform 3D\footnote{Note that here: '3D' does not mean a spatially explicit 3D pattern and hence the original ('old') way of specifying \textit{forcings}, but instead: that the forcing is applied uniformly in 3D space (i.e., is in effect a volume \textit{forcing}).} (volume), uniform 2D (surface), and point forcing, respectively, require no additional (spatial) information. Hence, with options \texttt{3}, \texttt{2}, or \texttt{0} set, only an additional file specifying the time-dependent information for each forcing need be provided, in files of the form:
\vspace{-10pt}\begin{verbatim}
biogem_force_flux_ocn_xxx_sig.dat
\end{verbatim}\vspace{-10pt}
for flux forcings, and 
\vspace{-10pt}\begin{verbatim}
biogem_force_restore_ocn_xxx_sig.dat
\end{verbatim}\vspace{-10pt}
where: \texttt{xxx} represents the mnemonic of the tracer (e.g., \texttt{DIC} is dissolved inorganic carbon. \texttt{CH4} is methane, etc.).

Options \texttt{-1} (\texttt{SURFACE}) and \texttt{-2} (\texttt{BENTHIC}) require a 2D field to be provided in addition to the time-dependent information for each forcing. The grids for both are the same -- i.e., all 'wet' grid points (non dry land) in the model. The filename for these 2D files is of the form:
\vspace{-10pt}\begin{verbatim}
biogem_force_flux_ocn_xxx_SUR.dat
\end{verbatim}\vspace{-10pt}
for flux forcings, and 
\vspace{-10pt}\begin{verbatim}
biogem_force_restore_ocn_xxx_SUR.dat
\end{verbatim}\vspace{-10pt}
for restoring \textit{forcings}.

Examples of point and 2D (benthic) ocean tracer \textit{forcing} are given below.
	
For details of the 'old', fully 3D spatially-explicit forcing methodology, refer to the \textit{c}GENIE \textit{user-manual}.


%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Prescribe a an injection of radiocarbon-dead DIC}\label{Prescribe a an injection of radiocarbon-dead DIC}

First ... a \textit{base-config} with 14C tracers is needed, e.g.,:
\vspace{-10pt}\begin{verbatim}
cgenie_eb_go_gs_ac_bg_itfclsd_16l_JH_ANTH
\end{verbatim}\vspace{-10pt}
\vspace{-10pt}\begin{verbatim}
cgenie_eb_go_gs_ac_bg_itfclsd_16l_JH_ANTHFe
\end{verbatim}\vspace{-10pt}
(with Fe co-limitation of marine biological productivity).

Then, in the \textit{user-config}, an appropriate \textit{forcing} needs to be specified, e.g.:
\vspace{-10pt}\begin{verbatim}
pyyyyx_FDIC_F13DIC_F14DIC
\end{verbatim}\vspace{-10pt}
and under the heading \texttt{--- FORCINGS ---}, might look something like:
 
\begin{compactitem}

	\item
	\vspace{-5pt}\begin{verbatim}
	bg_ctrl_force_oldformat=.false.
	bg_par_forcing_name="worjh2_FDIC_F13DIC_F14DIC"
	\end{verbatim}\vspace{-5pt}
	which prescribes a forcing of DIC plus its (13C and 14C) isotopes to the ocean (somewhere or everywhere).
	\item
	\vspace{-5pt}\begin{verbatim}
	bg_par_ocn_force_scale_val_03=0.0833e15
	\end{verbatim}\vspace{-5pt}
	sets the flux (mol yr-1), which is equivalent to 1 PgC yr-1.
	\item To scale the isotopic composition:
	\vspace{-5pt}\begin{verbatim}
	bg_par_ocn_force_scale_val_04=-60.0
	bg_par_ocn_force_scale_val_05=-999.0
	\end{verbatim}\vspace{-5pt}
	for example gives -60 per mil for 13C like methane and 14C that is pretty isotopically dead\footnote{Note this is on the scale of d14C not D14C}.
	\item By default in the \textit{forcing}, the duration of the emission 1 year, and can be re-scaled (e.g., to 1000 years duration) by: 
	\vspace{-5pt}\begin{verbatim}
	bg_par_ocn_force_scale_time_03=1000.0
	bg_par_ocn_force_scale_time_04=1000.0
	bg_par_ocn_force_scale_time_05=1000.0
	\end{verbatim}\vspace{-5pt}
	\item Finally -- the emission location is specified by, e.g.:
	\vspace{-5pt}\begin{verbatim}
	bg_par_force_point_i=18
	bg_par_force_point_j=26
	bg_par_force_point_k=7
	\end{verbatim}\vspace{-5pt}
	Alternatively, the DIC release can be made over the entire ocean floor or simply sections (or depth intervals) of 
the ocean floor instead of a point source.

\end{compactitem}


%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Prescribe a spatial map of benthic tracer release}\label{Prescribe a spatial map of benthic tracer release}

Flux \textit{forcings} to the ocean with a variety of different spatial attributes can be specified in the \textit{forcings} specification file: \texttt{configure\_forcings\_ocn.dat}. As detailed in the notes to this file, there is a flag (\texttt{COLUMN \#6}) which sets the spatial attributes of the \textit{forcing}: 
\vspace{-10pt}\begin{verbatim}
3 == 3D
2 == 2D
0 == point
-1 == SURFACE
-2 == BENTHIC
\end{verbatim}\vspace{-10pt}
with the default requiring a (3D) spatially explicit field to be provided.
Options \texttt{-1} (\texttt{SURFACE}) and \texttt{-2} (\texttt{BENTHIC}) require a 2D field to be provided. The grids for both are the same -- i.e., all 'wet' grid points (non dry land) in the model.
Templates for either can be created as follows:
\begin{compactenum}
\item Open up the \textit{BIOGEM} results file: \texttt{fields\_biogem\_2d.nc} (any experiment).
\item Display the variable: \texttt{grid\_mask}.
\item Select the \texttt{Array 1} tab (to display the actual gridded values rather than the color-coded map); highlight the grid of values and then copy-and-paste to a text editor.
\item You should have a grid of values, with a '\texttt{1.0}' representing ocean, and '\texttt{NaN}' land. The \texttt{NaN}s can then be search-and-replaced to '\texttt{0.0}' and you have a grid valid for either the entire surface ocean or entire benthic surface.
\end{compactenum}
From here: \texttt{1}s can be replaced by \texttt{0}s to remove unwanted locations.\footnote{This can be quite time-consuming and tedious and there is no particular short-cut :(}
In the forcing configuration file, if the \texttt{COLUMN \#5} flag ('\texttt{scale flux forcing of tracer?}') is set to 't', then the flux applied at each selected location is scaled such that the total applied flux is equal to that given in the \textit{forcing} time-signal file.\footnote{The values in the forcing map need not be all 1.0 of course.}


%---------------------------------------------------------------------------------------------------------------------------------
%--- HOW-TOs: Sediments and weathering -------------------------------------------------------------------------------------------
%---------------------------------------------------------------------------------------------------------------------------------

\newpage
\section{HOW-TOs: Sediments and weathering}\label{how-to-6}


%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Spin-up the full marine carbon cycle including sediments}\label{Spin-up the full marine carbon cycle including sediments}

By a 2-step process\footnote{This is a revised methodology compared to that described in the GENIE-1 HOW-TO.}:

\begin{compactenum}

	\item \textbf{First-guess '\textit{closed system}' \textit{spin-up}}
	\\As of \textbf{r4211} this it is possible to carry out the initial spin-up, \textbf{with} a solute input to the ocean via rivers, but also with the system configured 'closed', i.e.,:
\vspace{-5pt}\begin{verbatim}bg_ctrl_force_sed_closedsystem=.true.\end{verbatim}\vspace{-5pt}
The weathering flux is subtracted from ocean cells overlying the sediments to balance the global budget and ensure a closed system. This subtraction involves partitioning the total global weathering flux between each ocean floor cell with a subtraction in proportion to the estimated CaCO3 preservation and burial rate. To utilize this methodology now requires that the ROKGEM module is used, i.e., a \textit{base config} such as:
\vspace{-5pt}\begin{verbatim}cgenie_eb_go_gs_ac_bg_sg_rg_itfclsd_16l_JH_BASE\end{verbatim}\vspace{-5pt}
A first guess for the weathering flux must now be prescribed. This could be derived from a previous closed system model experiment with no weathering flux specified (diagnosing weathering from total global CaCO3 burial as described earlier), or from the literature, e.g., \textit{Ridgwell} [2007] cites 20 Tmol HCO3- yr-1, an equivalent CaCO3 weathering rate of 10 Tmol yr-1:
\vspace{-5pt}\begin{verbatim}rg_par_weather_CaCO3=10.00E+12\end{verbatim}\vspace{-5pt}

The following \textit{user config} file 
\vspace{-5pt}\begin{verbatim}EXAMPLE_worjh2_PO4_S36x36_SPIN\end{verbatim}\vspace{-5pt}
can be used for the closed system spin-up.

\noindent To launch an experiment, type (all in one line; notes space separators between line items in this document format):
\vspace{-5pt}\begin{verbatim}
./runCCSgenie.sh cgenie_eb_go_gs_ac_bg_sg_rg_itfclsd_16l_JH_BASE /
  EXAMPLE_worjh2_PO4_S36x36_SPIN 20001
\end{verbatim}\vspace{-5pt}

\noindent To submit to the cluster type:
\vspace{-5pt}\begin{verbatim}qsub -q kitten.q -j y -o cgenie_log -S /bin/bash subcgenie.sh
cgenie_eb_go_gs_ac_bg_sg_rg_itfclsd_16l_JH_BASE /
  EXAMPLE_worjh2_PO4_S36x36_SPIN 20001
\end{verbatim}\vspace{-5pt}

\noindent 20000 years (20001 if using the default \textit{time-series} saving points in order to record the last (annual averaged) year of the experiment) is probably about the minimum practical \textit{spin-up} time. Primarily -- you are looking for convergence in the mean wt\% CaCO3 value (averaged sediment composition), which is recorded in the \textit{BIOGEM} \textit{time-series} file:
\vspace{-5pt}\begin{verbatim}EXAMPLE_worjh2_PO4_S36x36_SPIN\end{verbatim}\vspace{-5pt}

	\item \textbf{Open system spin-up}
	\\The last stage is an open system spin-up as described previously. The prescribed weathering flux (\texttt{rg\_par\_weather\_CaCO3}) is revised and set equal to the diagnosed global CaCO3 burial rate ('\texttt{Total CaCO3 pres (sediment grid)}') as reported in the SEDGEM module results file:
\\\texttt{seddiag\_misc\_DATA\_GLOBAL.res}.
In addition, an \textit{open system} must now be specified in the \textit{user config}:
\vspace{-5pt}\begin{verbatim}bg_ctrl_force_sed_closedsystem=.false.\end{verbatim}\vspace{-5pt}

\noindent 50000 years (50001 if using the default \textit{time-series} saving points in order to record the last (annual averaged) year of the experiment) is probably about the minimum practical \textit{spin-up} time. Again -- you are looking for convergence in the mean wt\% CaCO3 value.

\end{compactenum}

There is still some departure of ocean Ca and ALK inventories during the revised multi-stage spin-up compared to observed (and the initialized values), but this is substantially reduced compared to the original 2-part spin-up methodology as well as to a single spin-up methodology.

\noindent \textbf{TIP}: Having completed the full marine carbon cycle spin-up, it is recommended that the CaCO3:rain ratio is set invariant -- see earlier HOWTO. If the default CaCO3 parameterization setting is retained, CO2-calcification feedback as described in \textit{Ridgwell et al.} [2007b] is enabled.

\noindent \textbf{NOTE}: There is no climate feedback by default. To run experiments with feedback between CO2 and climate, add:\vspace{-11pt}\begin{verbatim}ea_36=y\end{verbatim}\vspace{-11pt}
at the end of the \textit{user config}.


%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Run the sediments at higher resolution}\label{Run the sediments at higher resolution}

By default (as set in the \textit{base config} file in \texttt{\~{}/genie/genie-main/configs}) the SEDGEM sediment grid is configured at a resolution of 36x36 (and on an equal area grid), by:
\vspace{-5.5pt}\begin{verbatim}
SEDGEMNLONSOPTS='$(DEFINE)SEDGEMNLONS=36'
SEDGEMNLATSOPTS='$(DEFINE)SEDGEMNLATS=36'
\end{verbatim}\vspace{-5.5pt}
Several data input files are required by SEDGEM consistent with the specified grid:

\begin{compactitem}
	
	\item A mask, which specifies the sediment grid locations (if any!) at which 'sediment cores' (see: \textit{Ridgwell} [2007]) are to be generated at:
	\vspace{-5.5pt}\begin{verbatim}sg_par_sedcore_save_mask_name="sedgem_save_mask.36x36"\end{verbatim}\vspace{-5.5pt}
	The example provided on SVN contains some illustrative locations set (by a '\texttt{1}') for cores to be generated in.
	
	\item The required sediment grid topography (bathymetry):
	\vspace{-5.5pt}\begin{verbatim}sg_par_sed_topo_D="sedgem_topo_D.36x36"\end{verbatim}\vspace{-5.5pt}
	This particular grid is derived from observed bathymetry and excludes sediment locations shallower than the surface ocean layer (of the 8-level model) as described in Ridgwell and Hargreaves [2007].
	
\end{compactitem}

The directory location of the required files is set by input directory namelist setting, which by default is:
\\\texttt{sg\_par\_indir\_name="} \texttt{\$RUNTIME\_ROOT/genie-sedgem/data/input"}

As described in Ridgwell and Hargreaves [2007], SEDGEM can be sub-gridded to a resolution of 72x72 (equal area). The following namelist additions are necessary to the \textit{user config} file:
\vspace{-5.5pt}\begin{verbatim}
SEDGEMNLONSOPTS='$(DEFINE)SEDGEMNLONS=72'
SEDGEMNLATSOPTS='$(DEFINE)SEDGEMNLATS=72'
sg_par_sed_topo_D="sedgem_topo_D.72x72"
sg_par_sedcore_save_mask_name="sedgem_save_mask.72x72"
\end{verbatim}\vspace{-5.5pt}

\textbf{NOTE}: Carbonate chemistry stability problems (= model crash) may occur in the 16-level configuration in conjunction with 72x72 resolution sub-gridded sediments. Who knows why?! :(


%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Include shallow water depositional systems}\label{Include shallow water depositional systems}

\noindent \textbf{Relevant EXAMPLES}: 



%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Accelerate the weathering-sedimentation mass balance ('\texttt{GEMlite}')}\label{GEMlite}

\noindent \textbf{Relevant EXAMPLES}: 

\noindent \textbf{Also see}: \texttt{\textit{c}GENIE} user-manual 'FAQ' (further comments on \texttt{GEMlite} applicability).

\noindent A (pseudo) module is provided: '\texttt{GEMlite}' which provides a means of much more rapidly solving the weathering-sedimentation mass balance -- i.e. the long-term (>10 kyr) carbon cycle processes and feedbacks. The motivation behind \texttt{GEMlite} is the stark disparity between the time-scales of ocean circulation and biological pump (ca. 0.1-1000 years) and those of sedimentation and weathering (~2-20 kyr) and particularly the silicate weathering feedback (>100 kyr). This makes running \texttt{cGENIE} to an open system steady state (with or without the silicate weathering feedback) challenging. Is there any way of 'accelerating' the calculation of the 'long tail' [Archer et al., 2009] of the CO2 curve (e.g. in response to fossil fuel CO2 emissions)?

The philosophy is as follows: the long-term weathering-sedimentation processes are effectively just an imbalance between the supply of solutes via weathering and preservation and burial of esp. carbonates in deep-sea (and shallow) marine sediments. For a small imbalance between weathering and sedimentation, atmospheric pCO2 and climate (and hence the solute flux when including weathering feedbacks) will only change very slightly. For long intervals characterized by only a small imbalance in weathering-sedimentation the key assumption is made:
Ocean circulation and the biological pump, and hence the *gradients* of dissolved species in the ocean can be considered *invariant*.
Hence, for the purpose of solving weathering-sedimentation over an intervals of time:
The ocean can be treated as a *single box*.
It further assumes that:
The ocean is initially in equilibrium with the atmosphere (w.r.t. CO2).
(This latter assumption does place important limitations on under what circumstances \texttt{GEMlite} can be employed to accelerate experiments.)

This is what \texttt{GEMlite} does -- it solves for weathering-sedimentation and applies the mass difference *uniformly* throughout the ocean (as if it were a single box), hence preserving the tracer gradients in the ocean. It also (optionally) calculates and re-partitioning of carbon between ocean and atmosphere. Because ocean circulation and the biological pump etc. do not have to be re-calculated, the accelerated quasi box-model phase can be calculated very considerably faster than the 'full' model.
Obviously, if atmospheric pCO2 and hence climate are changing at an appreciable rate then the assumption of invariance in ocean tracer gradients breaks down and it is not 'safe' to apply the accelerated calculation. Similarly, appreciable changes in nutrient inventories will affect the biological pump and hence also change tracer gradients.

The key to employing \texttt{GEMlite}, in addition to knowing when it is appropriate/not appropriate to employ it, is to decide what balance of accelerated (\texttt{GEMlite}) time-stepping vs. normal (full system update of ocean circulation, biological pump, etc.) time-stepping to employ. This division is implemented by creating a sequence of accelerated vs. non-accelerated time-stepping. This can be done in one of two ways:

\begin{compactenum}
	
	\item Fixed sequence.
	\\By default, \texttt{GEMlite} will employed a fixed, pre-determined sequence of accelerated vs. non-accelerated time-stepping. The parameters to specify this sequencing are:
	\\\texttt{ma\_gem\_notyr} -- which sets the number of years (the assumed time-step of \texttt{GEMlite}) for 'normal' time-stepping.
	\\\texttt{ma\_gem\_yr} -- which sets the number of years for accelerated time-stepping.
\\For instance: if \texttt{ma\_gem\_notyr=50} and \texttt{ma\_gem\_yr=50}, you would have a sequence with 50 years of full updating, followed by 50 years of accelerated.
\\For instance: if \texttt{ma\_gem\_notyr=10} and \texttt{ma\_gem\_yr=90}, you would have a sequence with 10 years of full updating, followed by 90 years of accelerated.
\\etc.
\\Note that the GEMlite cycle phase of 'normal' time-stepping is *always* done first.
\\Also note that choosing e.g. \texttt{ma\_gem\_notyr=10} and \texttt{ma\_gem\_yr=100}, while appearing a desirably simple ratio, would result in the change-over point in cycle phase (to accelerated) occurring at the end of year 10, 120, 230, 240, etc. -- something that might affect/influence your choice of data saving pattern (i.e., the sequence of time-points for time-series and time-slice data saving).
\\By default, the parameter values are: \texttt{ma\_gem\_notyr=999999} and \texttt{ma\_gem\_yr=1} meaning that in practice you will never get to the end of the 'normal' time-stepping phase. Note that these parameters are \textbf{integers} (setting real numbers, e.g. \texttt{1.0E6} will not work ...).

	\item Adaptive sequencing.
	\\Here, \texttt{GEMlite} attempts to be clever and optimizes the ratio between the duration of each phase of the cycle.
	\\The motivation for this is that often in model experiments, environmental parameters will  tend to change faster at the beginning of an experiment compared to towards the end. Fossil fuel CO2 release and its long tail of declining pCo2 is a good example of this. Obviously this complicates the choice of a (fixed) ratio of cycle phases -- 100:100 (or more likely: 1000:1000) might not lead to too much degradation of the simulation, but you would only gain a speed advantage of x2 for the experiment as a whole, which if ~100-1000 kyr in total duration, is still going to be l o n g. On the other hand: 10:90 would give you a factor almost x10 increase in overall speed, but would seriously degrade the simulation during the initial, rapidly changing environment following CO2 release.
	\\Adaptive sequencing adjust the time-stepping via 2 criteria:
\begin{compactitem}
	\item In the normal time-stepping phase, if the rate of change of pCO2 is *more than* a specified threshold over any one year, then the total duration of this phase is extended by one year.
	\item In the accelerated time-stepping phase, if the total change in pCO2 since the last normal phase is *less than* a specified threshold, then the total duration of this phase is extended by one year.
\end{compactitem}
The result is that the phase durations are always a minimum of the values set by \texttt{ma\_gem\_notyr} and \texttt{ma\_gem\_yr}. If it is 'unsafe' to switch to accelerated mode, because pCO2 is changing rapidly, then the model stays in normal mode. If it is safe to stay in the accelerated mode, because pCO2 has not changed much in total during the phase, then the model stays in the accelerated phase.
	\\The parameter names are default values for the two thresholds are:
\begin{compactitem}
	\item \texttt{ma\_gem\_adapt\_dpCO2dt=0.1} (ppm yr-1)
	\item \texttt{ma\_gem\_adapt\_DpCO2=1.0} (ppm)
\end{compactitem}
but these will not necessarily be the ideal of any particular experiment (and some trial-and-error ma be called for).
\\Adaptive time-stepping is enabled by setting:
\\\texttt{ma\_gem\_adapt\_auto=.true.}
\\(by default it is \texttt{.false.}).
\\The switching between normal (non accelerated) and accelerated phases is saved in a time-series file:
\vspace{-5pt}\begin{verbatim}biogem_series_misc_gemlite.res\end{verbatim}\vspace{-5pt}

As a further refinement, the accelerated phase can be set to be relatively short to begin with, but gradually increasing in length. The parameters controlling this are:
\\\texttt{ma\_gem\_yr} -- the initial accelerated phase duration
\\\texttt{ma\_gem\_yr\_max} -- the maximum accelerated phase duration
\\\texttt{ma\_gem\_adapt\_dgemyr} -- the (minimum) fractional increase in duration each cycle (or 1.0 yr, whichever is greater)
\\ A reasonable set of parameters:
\vspace{-5pt}\begin{verbatim}
ma_gem_notyr=10
ma_gem_yr=10
ma_gem_yr_max=990
ma_gem_adapt_dgemyr=0.05
ma_gem_adapt_dpCO2dt=0.10
ma_gem_adapt_DpCO2=0.01
ma_gem_adapt_auto=.true.
ma_gem_adapt_auto_unlimitedGEM=.false.
\end{verbatim}\vspace{-5pt}
	
\end{compactenum}

Finally ... you will need a \textit{base-config} that has \texttt{GEMlite} enabled.
This actually requires nothing more than the addition of a couple of lines (to a \textit{base-config} file): 
\vspace{-10pt}\begin{verbatim}
ma_flag_gemlite=.TRUE.
\end{verbatim}\vspace{-10pt}
which can go e.g. near the start of the file under \texttt{\# GENIE COMPONENT SELECTION}.
Plus:
\vspace{-10pt}\begin{verbatim}
ma_kgemlite=xx
\end{verbatim}\vspace{-10pt}
which can go e.g. under \texttt{\# TIME CONTROL AND TIME-STEPPING}.
\\Here, \texttt{xx} will depend on the time-step assumed in the base-config. This is likely to be either \texttt{96}: the standard for most \textit{base-configs}, or \texttt{48}: for low resolution and faster model configurations, which typically have \texttt{.t48} in their filename.
By convention, I name \textit{base-configs} including \texttt{GEMlite} with \texttt{\_gl},
\\e.g. \texttt{cgenie\_eb\_go\_gs\_ac\_bg\_sg\_rg\_gl.p0000c.BASESLi.t48.config}
\\but you can name it \texttt{BobTheLeglessPony} for all I care.

The \textbf{most important} thing is to ensure you are not seriously degrading model fidelity (of carbon cycle simulation) by your adoption and configuration of \texttt{GEMlite}.
\\\textbf{Test} different assumptions of how the time-stepping phases are scheduled and compare (of possible) against a full experiment in which \texttt{GEMlite} is not used.

It is important to recognize that when the model switches into the GEM phase, it assumes all ocean tracer gradients are fixed, and updates only ocean composition as a whole according to weathering vs sedimentation imbalance (and also tries to re-equilibrium ocean and atm). As part of this, the flux to the sediments is taken from the average of the last year of the preceding normal phase, and fixed. This also means that the d13C of the CaCO3 deposited to the sediments is fixed ... even if the ocean d13C is being updated and changing ... So, basically you lose the feedback that leads to d13C converging as sinks balance (weathering and volcanic) inputs\footnote{Adjusting the fluxes themselves during the GEM intervals would break the underlying assumption inherent in the acceleration approximation.}.
\\The solution is to not run in the GEM phase for such long intervals -- instead giving the normal phase a chance to make a brief update of ocean gradients and also d13C of export flux. BUT, if pCO2 hardly changes, \textit{c}GENIE runs the risk of staying in the GEM phase for ever (ish)!
\\ A further option:
\vspace{-5pt}\begin{verbatim}
gem_adapt_auto_unlimitedGEM
\end{verbatim}\vspace{-5pt}
sets whether GEM is allowed an unlimited phase duration or not. By default it is \texttt{.false.}. This means that the maximum GEM duration is limited to the normal \texttt{gem\_yr} parameter. Also, if excessive (pCO2) drift occurs, the model will immediately switch to the normal phase.

By default then:
\begin{compactitem}
	\item \texttt{gem\_notyr} specifies a MINIMUM duration for a normal phase..
	\item \texttt{gem\_yr} specifies a MAXIMUM duration for a GEM phase.
\end{compactitem}
Values of \texttt{gem\_yr} much less than 100 are not advisable as you will not reestablish a new equilibrium gradient of tracers in the ocean in that time.


%---------------------------------------------------------------------------------------------------------------------------------
%--- HOW-TOs: Visualization ----------------------------------------------------------------------------------------------------
%---------------------------------------------------------------------------------------------------------------------------------

\newpage
\section{HOW-TOs: Visualization}\label{how-to-7}


%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Generate ensembles and visualize their output using Mathematica}\label{Generate ensembles and visualise their output using Mathematica}

Use the scripts in \texttt{genie-tools/runscripts}. Read the \texttt{READ\_ME} file in this directory for instructions. The Mathematica notebooks allow for easy ensemble generation across multiple variables (still using non-XML version though!), and also for interactive plotting of time-series and netcdf data with GUIs - including comparisons and movies etc. (note: you can get a free trial of Mathematica if you don't have access to it).


%---------------------------------------------------------------------------------------------------------------------------------
%--- HOW-TOs: Miscellaneous -------------------------------------------------------------------------------------------
%---------------------------------------------------------------------------------------------------------------------------------


\newpage
\section{HOW-TOs: Miscellaneous}\label{how-to-8}

%---------------------------------------------------------------------------------------------------------------------------------


\subsection{Speed up the model}\label{Speed up the model}

*sign* You speed freak. Is this all you care about? What about the 'quality' of the simulation - does that mean absolutely nothing to you? Oh well ...
There is a bunch of stuff that slows GENIE down that may not be absolutely essential to a particular model experiment. These include:
\begin{compactenum}
	\item	The number of tracers - if you don't need 'em, then don't select 'em! Selected tracers are automatically passed to GOLDSTEIN and advected/convected/diffused with ocean circulation. Similarly, BIOGEM does a whole bunch of stuff with tracers, particularly those which can be biologically transformed. All this is numerically wasteful if you aren't interested in them. Equally importantly, the more tracers you have selected the more careful you have to be in configuring the model. Superfluous tracers therefore cost more configuration time and/or increase the change of a model crash.
	\item 'Tracer auditing' - the  continuous updating and checking global tracer inventories to ensure that there is no spurious loss or gain of any tracer (i.e., a bug) has computational overheads associated with it. Whether this checking is carried out or not is set by the value of the flag \texttt{bg\_ctrl\_audit}\footnote{It is \texttt{.false.} by default.}.
	\item Time-series results saving. Model tracer (plus some 'physical') properties are bring continuously averaged in constructing time-series results files. Cutting down on time-series that you don't need will help minimize model run-time. The various categories of time-series that will be saved are specified by a series of namelist parameter flags. However, within each category (such as \texttt{ocn} tracers - \texttt{bg\_ctrl\_data\_save\_sig\_ocn}) all properties will be saved - you are not given to option to save a defined sub-set (for example, DIC and PO4 in the ocean but not ALK). Note that time-series saving of data that is a 2-D average, such as atmospheric composition at the ocean-atmosphere interface, sediment composition at the ocean-sediment interface, or just ocean surface conditions, is less numerically demanding than mean values that have to be derived from a 3-D data field.
	\item Time-slice results saving. If you have relatively few requested time-slices over the course of the model integration then this is unlikely to significantly impact the overall run-time (even will all possible data category save namelist flags set to \texttt{.true.}). However, note that if you have accidently triggered the default time-slice saving interval (by having no data items in the time-slice specification file (\texttt{bg\_par\_infile\_slice\_name}) you may end up with the model running about as fast as a 2-legged dog super-glued to a 10-tonne biscuit.
	\item Alter the degree of asynchronicity between climate and biogeochemistry (see later HOW-TO).
\end{compactenum}

As a very rough guide, the impact on total run-time of making various changes to the model configuration are listed as follows. Numbers are given as a percentage increase in total model run-time (using the /usr/bin/time linux command). Tracers selected in the ocean are DIC, ALK, PO4, O2, DOM\_C, DOM\_P, DOM\_O2, as well as 13C isotopic components (DIC\_13C and DOM\_C\_13C) (+ T and S). The corresponding tracers are present in the atmosphere and as particulates. The model is run for 10 years as a new run (i.e., not loading in a restart file):

\begin{compactitem}
	\item	ADD auditing \begin{math}\Rightarrow\end{math} +15\%
	\item	ADD time-slice saving	\begin{math}\Rightarrow\end{math} +20\%\footnote{Because only a 10 year integration has been carried out with a time-slice saved at 10 years, the computational cost of time-slice saving is disproportionately high as displayed. With a longer integration, the relative cost of saving a time-slice will fall. In constrast, the computational cost as a fraction of total run-time of time-series saving and auditing is likely to remain the same.}
	\item	ADD time-series saving	\begin{math}\Rightarrow\end{math} +15\%
	\item	REMOVE \begin{math}^{13}\end{math}C isotopic species (= DIC and DOC ocean tracers) \begin{math}\Rightarrow\end{math} -10\%\footnote{The speed gained by removing two tracers is not proportional to the fractional decrease in number of tracers (in this example reducing from 11 to 9 the number of tracers in the ocean gives only a ca. 10\% improvement in overall speed).}
\end{compactitem}

The basic configuration for a faster 'lego box' cGENIE configuration consists of a 18x18 model grid and an 8 level ocean. The continents are in a zonally-averaged configuration and there is no topography in the oceans.
\\
The model is accelerated by:\\
(a) it's low resolution\\
(b) taking 48 instead of 96 ocean timesteps per year \\
(c) BIOGEM is only being updated every 4 rather than every 2 ocean time-steps.
\\
Note: I am still in the process of carrying out numerical stability tests; in the end it may have to slow down a bit.

Because the time-stepping is different a new \textit{rungenie} (make executable) script has to be used:
\vspace{-5.5pt}\begin{verbatim}
runCCSgenie_t48.sh
\end{verbatim}\vspace{-16.5pt}
  (an equivalent ocean-only full carbon cycle including sediments has yet to be created!)
\\
Using the following example \textit{user config}:
        \vspace{-5.5pt}\begin{verbatim}
 EXAMPLE_p0000b_SPIN_x1CO2_S18x18
  \end{verbatim}\vspace{-16.5pt}
                and base config:
 \vspace{-5.5pt}\begin{verbatim}
 cgenie_eb_go_gs_ac_bg_sg_rg_modern_18x18x8_0i_BASE_t48.config
  \end{verbatim}\vspace{-16.5pt}
                A typical run would look like something like:
      \vspace{-5.5pt}\begin{verbatim}
./runCCSgenie_t48.sh
  cgenie_eb_go_gs_ac_bg_sg_rg_modern_18x18x8_0i_BASE_t48 /
  EXAMPLE_p0000b_SPIN_x1CO2_S18x18 101
 \end{verbatim}\vspace{-16.5pt}
                (Don't forget to do a make cleanall if you were using a different ocean configuration!)
\\
In this configuration 100 years take about 40 seconds, 10 kyr would just take over and hour, and 100 kyr could be run overnight!


%---------------------------------------------------------------------------------------------------------------------------------

\subsection{Chop genie runs into manageable pieces (useful for very long runs)}\label{Chop genie runs into manageable pieces (useful for very long runs)}

Use the scripts in \texttt{genie-tools/runscripts}. Read the \texttt{READ\_ME} file in this directory for instructions.

%---------------------------------------------------------------------------------------------------------------------------------


%---------------------------------------------------------------------------------------------------------------------------------
%--- Contact Information ---------------------------------------------------------------------------------------------------------
%---------------------------------------------------------------------------------------------------------------------------------

\newpage
\section{Contact Information}

\begin{compactitem}
	\item Andy Ridgwell: \texttt{bandy@seao2.org}
\end{compactitem}



%=================================================================================================================================
%=== END DOCUMENT ================================================================================================================
%=================================================================================================================================

\end{document}

